Graphics Plus/Graphics Plus.iso/general/modelers/geomview/source.lha/Geomview/doc/OOGL.m.doc

Text File | 1993-12-06 | 17KB | 418 lines

NOTE: This file is autogenerated from the Geomview manual.
  For references to things not in this file, see the manual.
  The manual is distributed in the "doc" subdirectory.


Mathematica Graphics in Geomview or RenderMan
*********************************************

Geomview comes with some Mathematica packages that let you use use
Geomview to display Mathematica graphics.  Mathematica is a commercial
mathematical software system available from Wolfram Research, Inc.

There are two ways to do this.
  1. Use Mathematica to write a graphics object to a file in OOGL format
     or in RIB format.
  2. Use Geomview as the default display for all 3D graphics output in
     Mathematica.
You can also use these packages to save Mathematica graphics in
RenderMan (RIB) format.

Since the format of Mathematica graphics objects is different from the
OOGL formats, both of these methods involve translating Mathematica
graphics to OOGL format.  Geomview is distributed with a Mathematica
package which does this translation.  Before doing either of the
above you must install this package.

Info file: geomview,    -*-Text-*-
produced by texinfo-format-buffer
from file: geomview.tex



Using Mathematica to generate OOGL files
========================================

The package `OOGL.m' allows Mathematica to write graphics objects in
OOGL format.  To use it, give the command `<< OOGL.m' to Mathematica to
load the package.  The `WriteOOGL[FILE,GRAPHICS]' command writes an OOGL
description of the 3D graphics object GRAPHICS to the file named FILE.

This package also provides the `Geomview' command which sends a
3D graphics object to Geomview.  The first time you use this command
it starts up a copy of Geomview.  Later calls send the graphics to the
same Geomview.  There are two ways to use the `Geomview' command.

`Geomview[GRAPHICS]'
     Sends the 3D graphics object GRAPHICS to Geomview as a geom named
     `Mathematica'.  Subsequent usage of `Geomview[GRAPHICS]'
     replaces the `Mathematica' object in Geomview with the new
     GRAPHICS.

``Geomview[NAME,GRAPHICS]''
     Sends the 3D graphics object GRAPHICS to Geomview as a geom named
     NAME.  You can use multiple calls of this form with different
     names to cause Geomview to display several Mathematica objects at once
     and allow independent control over them.
     % math
     Mathematica 2.0 for SGI Iris
     Copyright 1988-91 Wolfram Research, Inc.
      -- GL graphics initialized --

     In[1] := <<OOGL.m

     In[2] := Plot3D[Sin[x + Sin[y]], {x,-2,2},{y,-2,2}]

     Out[2] := -Graphics3D-
This displays graphics in the usual Mathematica way here.
     In[3] := WriteOOGL["math.oogl", %2]

     Out[3] := -Graphics3D-
This displays nothing new but writes the file `math.oogl'.
You can now load that file into Geomview on any computer.  Alternately,
you can use the `Geomview' command to start up a copy of Geomview
from within Mathematica.
     In[5] := Geomview[%2]

     Out[5] := -Graphics3D-



Using Geomview as Mathematica's Default 3D Display
==================================================

The package `Geomview.m' arranges for Geomview to be the
default display program for 3D graphics in Mathematica.  To
load it, give the command `<< Geomview.m' to Mathematica.
Thereafter, whenever you display 3D graphics with `Plot3D'
or `Show', Mathematica will send the graphics to Geomview.

Loading `Geomview.m' implicitly loads `OOGL.m' as well, so you
can use the `Geomview' and `WriteOOGL' as described above
after loading `Geomview.m'.  You do not have to separately load
`OOGL.m'.
     % math
     Mathematica 2.0 for SGI Iris
     Copyright 1988-91 Wolfram Research, Inc.
      -- GL graphics initialized --

     In[1] := <<Geomview.m

     In[2] := Plot3D[x^2 + y^2, {x, -2, 2}, {y, -2, 2}]

     Out[2] := -SurfaceGraphics-
This invokes geomivew and loads the graphics object into it.
     In[3] := Plot3D[{x*y + 6, RGBColor[0,x,y]}, {x,0,1}, {y,0,1}]

     Out[3] := -SurfaceGraphics-
This replaces the previous Geomview object by the new object.
     In[4] := Geomview[{%2,%3}]

     Out[4] := {-SurfaceGraphics-, -SurfaceGraphics-}
This displays both objects at once.  You also can have more than one
Mathematica object at a time on display in Geomview, and have separate
control over them, by using the `Geomview' command with a name,
*Note OOGL.m::.
     In[5] := Graphics3D[ {RGBColor[1,0,0], Line[{ {2,2,2},{1,1,1} }] }]

     Out[5] := -Graphics3D-

     In[6] := Geomview["myline", %5]
This addes the `Line' specified in `In[5]' to the existing
Geomview display.  It can be controlled independently of the
"Mathematica" object, which is currently the list of two plots.
     In[7] := <<GL.m
If you're on an SGI, loading `GL.m' returns Mathematica to its
usual 3D graphics display.  To do this on a NeXT you should load
`PSDirect.m' if you are using Mathematica in a notebook, or
`NeXT.m' if you invoked Mathematica from a shell.  The following
plot will appear in a normal static Mathematica window.
     In[8] := ParametricPlot3D[{Sin[x],Sin[y],Sin[x]*Cos[y]}, {x,0,Pi},{y,0,Pi}]

     Out[8] := -Graphics3D-
We can return to Geomview graphics at any time by reloading `Geomview.m'.
     In[9] := <<Geomview.m

     In[10] := Show[%8]

     Out[10] := -Graphics3D-

     In[11] := ParametricPlot3D[
            {(2*(Cos[u] + u*Sin[u])*Sin[v])/(1 + u^2*Sin[v]^2),
            (2*(Sin[u] - u*Cos[u])*Sin[v])/(1 + u^2*Sin[v]^2),
            Log[Tan[v/2]] + (2*Cos[v])/(1 + u^2*Sin[v]^2)},
           {u,-4,4},{v,.01,Pi-.01}]

     Out[11] := -Graphics3D-
This last plot is Kuen's surface, a surface of constant negative
curvature.  Parametrization from Alfred Gray's *Modern Differential
Geometry of Curves and Surfaces* textbook.


Using Mathematica to generate RenderMan files
=============================================

In addition to the `WriteOOGL' and `Geomview' commands
described above, the package `OOGL.m' also defines the command
`WriteRIB' which writes a 3D graphics object to a RenderMan RIB
file:  `WriteRIB[FILE, GRAPHICS]' writes GRAPHICS
to file FILE.  RenderMan is a commercial rendering system available
from Pixar, Inc., which can produce extremely high quality images.
     In[1] := <<OOGL.m

     In[2] := <<Graphics/Polyhedra.m

     In[3] := Graphics3D[Cube[]]

     Out[3] := -Graphics3D-

     In[4] := WriteRIB["cube.rib", %3]

     Out[4] := -Graphics3D- This generates the file `math.rib'.  This is
a ready-to-render RIB file of the given geometry, using a default camera
position, lighting, and the "plastic" shader. In a shell window, type
`render cube.rib' to generate the image file `mma.tiff'. Of course, you
need to have RenderMan installed for this to work. A shortcut to render
from inside Mathematica is `WriteRIB["!render", foo]'.

`WriteRIB' works by first converting the Mathematica graphics
object to OOGL format using `WriteOOGL' and then calls an external
program `oogl2rib' to convert OOGL to RIB format.  The
oogl2rib program takes several options which you can specify in a
string as an optional third argument to `WriteRIB'.  The default
option string is `" -n mma.tiff "', which indicates that the RIB
file should generate a rendered TIFF file named `mma.tiff'.  A
particularly useful option is `-g', which tells oogl2rib to
convert only the geometry into a RIB fragment. You can insert that
fragment into a full RIB file of your own making with camera positions
and shaders of your choice, to harness the full power of RenderMan.

The full usage of oogl2rib is:
     oogl2rib [-n NAME] [-B R,G,B] [-w WIDTH] [-h HEIGHT] [-fgb] [INFILE] [OUTFILE]
By default it reads from stdin and writes to stdout.
Either INFILE or OUTFILE may be `-', which means
use stdin/stdout.  The options are:

`-n NAME'
     Use NAME for the name of the rendered TIFF file (default
     "geom.tiff") or framebuffer window (default "geom.rib").

`-B R,G,B'
     Use background color (R,G,B).  Each component ranges
     from 0 to 1. Default: none.

`-w WIDTH -h HEIGHT'
     Rendered frame will be WIDTH by HEIGHT pixels.

`-f'
     RIB file renders to on-screen framebuffer instead of TIFF file.

`-g'
     Output only the geometry in RIB format.

`-b'
     Output only a Quick Renderman clip object.  Ignores -nBwhf.




Using Geomview and Mathematica on Different Computers
=====================================================

It is possible to use Geomview to display graphics generated by
Mathematica running on a different computer.  If each computer is either
an SGI or a NeXT and they are networked together, you can tell
Mathematica to use a remote host for Geomview graphics.  If you want to
use Mathematica on a computer that is not networked with your Geomview
computer, or on any kind of computer other than an SGI or a NeXT (for
example a PC or a Mac), you can write out *chunk* files in
Mathematica which you transfer to the Geomview computer and then
translate to OOGL format.

Using a Networked Geomview Host
-------------------------------

The `Geomview' command looks at the `DISPLAY' or
`REMOTEHOST' environment variables to try to determine if you are
logged in from another computer.  If either of these indicates that you
are, `Geomview' will attempt to run Geomview on that
computer.  In order for this to work, your network must be configured
such that the Mathematica computer can successfully `rsh' to the
Geomview computer without giving a password.

You can also explicitly set the `DisplayHost' option to the
`Geomview' command to a string which is the desired hostname, for
example:
     In[1] := << OOGL.m

     In[2] := Plot3D[Sin[x + Sin[y]], {x,-2,2},{y,-2,2}]

     Out[2] := -Graphics3D-

     In[3] := Geomview[%3, DisplayHost->"riemann"] This displays the
graphics `%3' on the remote host named `riemann'.

`Geomview' recognizes the string `"local"' as a value for
`$DisplayHost'; it forces the graphics to be displayed on the local
machine.

In addition to knowing the name of the machine you want to run Geomview
on, the `Geomview' needs to know the type of that machine (SGI or NeXT).
By default, `Geomview' assumes that it is the same kind of computer as
the one you are running Mathematica on.  The `MachType' option lets you
explicitly specify the type of the `DisplayHost' computer; it should be
one of the strings `"sgi"' or `"next"'.

You can use `SetOptions' to change the default `DisplayHost'
and `MachType'.  For example,
     In[4] := SetOptions[Geomview, DisplayHost->"riemann",
MachType->"sgi"] arranges for `Geomview' to run Geomview on an SGI
workstation named `riemann'.


Transporting Mathematica Files to Geomview by Hand
--------------------------------------------------

The auxilliary function `WriteChunk' is for those who can only use
Mathematica on a non-Unix machine (Mac, PC) or a Unix machine that is
not on a network with an SGI or NeXT.  `WriteChunk[FILE, GRAPHICS]'
generates a file named FILE which contains the graphics object GRAPHICS
in the format accepted by `math2oogl'.

You can transfer that file to a computer that has Geomview installed on
it and then use the programs `math2oogl', `oogl2rib', and
`geomview' directly from the shell.  These programs are distributed
in the `bin/sgi' (on SGIs) or `bin/next' (on NeXTs)
subdirectory of the Geomview directory, and may have been installed so
that they are on your `path'.

     In[1]:= <<OOGL.m

     In[2]:= Plot3D[ Sin[x + Sin[y]], {x,-2,2}, {y,-2,2} ]

     Out[2]= -SurfaceGraphics-

     In[3]:= WriteChunk["mychunk",%2]
This writes the file `mychunk' which contains a description
of the graphics object.  You can then transfer this file to an SGI or
NeXT and type
     math2oogl < mychunk > mma.oogl
to convert it to the OOGL file `mma.oogl' which you can then view
using Geomview. This is the equivalent of the `WriteOOGL' command.

For a result equivalent to the `Geomview' or `Show'
commands, type
     math2oogl -togeomview Mathematica geomview < mychunk

The `WriteRIB' command can be emulated from the shell as
     math2oogl < mychunk | oogl2rib -n mma.tiff





Details of the Mathematica->Geomview Package
============================================

The `OOGL.m' package uses the external program `math2oogl' to
convert `Graphics3D' objects to OOGL format, because a compiled
external program is able to do this conversion many times faster than
Mathematica.

The converter will sometimes handle colored SurfaceGraphics objects
correctly that Mathematica does not handle correctly, which means that
Geomview[object] sometimes works where Show[object] will give errors.

The converter supports the `Polygon', `Line', and `Point'
graphics primitives, `RGBColor Graphics3D' directives, and
`SurfaceGraphics' objects with or without `RGBColor'
directives, and lists of any combination of these. It silently ignores
all other directives.

The Mathematica to RenderMan conversion is actually a two-step process:
Mathematica->OOGL (math2oogl), and OOGL->RenderMan (oogl2rib). The
math2oogl program has only been tested on SGIs and NeXTs, but could
theoretically compile on any machine. The oogl2rib program depends on
the OOGL (Object Oriented Graphics Language) libraries, which now only
exist on SGI and NeXT machines.

In the `WriteOOGL' and `WriteRIB' commands, filename can either be a
string containing a filename, an `OutputStream' object, or a string
starting with a `!' to send the output to a command.  Object can be a
`Graphics3D' object, a `SurfaceGraphics' object, or a list of these.

The packages work best with Mathematica 2.0 or better.  With version 1.2,
the Geomview display is always on the local host.


Installing the Mathematica Packages
===================================

If Geomview is properly installed on your system according to the
instructions in *Note Installation::, then the Mathematica-to-Geomview
packages should work as described here; there should be no need for
additional installation procedures.  In practice, however, it is
sometimes necessary to taylor the installation of the Mathematica
packages and/or of Geomview itself to suit the needs of a particular
system.  This section contains details about how the installation works;
if the Mathematica-to-Geomview connection does not seem to work for you
after following the Geomview installation procedure, consult this
section to see what might need to be fixed.

In this section, the phrase *Geomview installation* refers any of
the procedures in *Note Installation::.  The way the Mathematica packages
work and are installed is the same regardless of whether you have
one of the binary distributions or the source distribution.


  1. The relevant mathematica files are `OOGL.m', `Geomview.m', and
     `BezierPlot.m'; Mathematica must be able to find these files.  They
     are distributed in the `$GEOMROOT/mathematica' subdirectory of the
     binary distributions, and in the
     `$GEOMROOT/src/bin/geomutil/math2oogl' subdirectory of the source
     distribution.  These files need to be in a directory that is on
     Mathematica's search path.  You can look at the value of the
     `$Path' variable in a Mathematica session on your system to see a
     list of the directories on Mathematica's search path.

     The Geomview installation procedure puts copies of the Mathematica
     packages into a directory that you specify (`MMAPACKAGEDIR').  This
     should ensure that Mathematica can find them.  Alternately, you could
     arrange to append the pathname of the Mathmematica package subdirectory
     of the Geomview distribution to the `$Path' variable each time you
     run Mathematica.

  2. The package `OOGL.m' needs to be able to invoke the programs
     `geomview', `math2oogl', and `oogl2rib'.  The Geomview
     installation procedure installs these programs into a directory that you
     specify for executables (`BINDIR').  Ideally, this directory should
     be on your shell's `$path'.  More specifically, it should be on
     the `$path' of the shell in which Mathematica runs; the directory
     `/usr/local/bin' is usually a good choice.  You can see the list of
     directories on this path by giving the command `!echo $path' in
     Mathematica.

     If for some reason you can't arrange for `geomview',
     `math2oogl', and `oogl2rib' to be in a directory on the
     shell's `$path', you can modify `OOGL.m' to cause it to look
     for them using absolute pathnames.  To do this, change the definitions
     of the variables `$GeomviewPath' and `$GeomRoot', which are
     defined near the top of the file.  Change `$GeomviewPath' to the
     absolute pathname of the `geomview' shell script on your system.
     Change `$GeomRoot' to the absolute pathname of the
     `$GEOMROOT' directory on your system.  If you do this, you should
     also make sure there are copies of `geomview', `math2oogl',
     and `oogl2rib' in the `$GEOMROOT/bin/sgi' (on an SGI) or
     `$GEOMROOT/bin/next' (on a NeXT) directory.

  3. The `geomview' shell script, which `OOGL.m' uses to invoke
     Geomview, needs to be able to find the geomview executable file (which
     is called `gvx' on the SGI and `Geomview.app/Geomview' on the
     NeXT).  The Geomview installation procedure should have been taken care
     of this, but if your Mathematica session doesn't seem to be able to
     invoke Geomview, it's worth double-checking that the settings in the
     `geomview' script are correct.